<!DOCTYPE HTML>
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta charset="utf-8">
<link rel="STYLESHEET" href="../book.css" type="text/css">
<script src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
<title>Cheat sheet authoring guidelines</title>
</head>
<body>

<h2>Cheat Sheet Authoring Guidelines</h2>

<p>
Cheat sheets and composite cheat sheets enable a user to achieve a goal by 
completing a sequence of steps. These guidelines discuss when to use cheat 
sheets and how to best write a cheat sheet. </p>

<h3>When to Create Cheat Sheets</h3>

<p>
Cheat sheets are well suited to tasks which consist of&nbsp; steps which lead 
towards a tangible goal, such as building a simple application. The goal must be 
well defined so that the user can see success when all the steps in cheat sheet 
have been completed. Tutorials are often good candidates for cheat sheets, in a 
tutorial the goal is to learn how to perform a specific task. Cheat sheets will 
usually contain up to 10 steps and can be completed in a half an hour or less. 
For larger tasks consider using a composite cheat sheet. </p>

<h3>When to Create Composite Cheat Sheets</h3>

<p>
Composite cheat sheets are used to for 
providing guidance through a task which is too large to describe in a single 
cheat sheet or which has multiple goals. A composite cheat sheet can be used to 
describe a sequence of tasks each of which builds on its predecessor. </p>

<h3>When Not to Use Cheat Sheets</h3>

<p>
Cheat sheets work best when problem can be solved by a sequence of simple steps. Cheat sheets are not a substitute for the help system which allows for 
creation of HTML pages with rich graphics and random access of information using 
search and hyperlinks. Cheat sheets are not intended for tasks which require a 
large amount of text to be input by the user. </p>
<h3>Guidelines for Creating a Cheat Sheet</h3>
<ul>
  <li>Choose a short and meaningful title.</li>
  <li>Utilize links to the help system in cheat sheet tasks whenever possible to 
  provide background or more detailed information</li>
  <li>Consider rewriting as a composite cheat sheet if there are more than 10 
  steps.</li>
  <li>Utilize commands where possible to perform simple tedious tasks such as 
  opening perspectives, opening resources, executing wizards. Be sure to also 
  provide a description of how to achieve the same effect without using the 
  command.</li>
  <li>&nbsp;Ensure commands can be skipped if the user decides to do the steps 
  manually</li>
  <li>Specify dialog=&quot;true&quot; for steps which open dialogs. This will cause the 
  cheat sheet to open in a &quot;tray&quot; to the right of&nbsp; most dialogs.</li>
  <li>Organize the steps in such a way that the user sees visible signs of 
  success frequently. A cheat sheet that makes a number of different changes to 
  java source and then launches an application could be rewritten so that the 
  application was launched after each source change.</li>
  <li>Make sure the user understands why they are performing each step.</li>
  <li>Rather than describing multiple ways to perform&nbsp; a step pick the 
  simplest way requiring the least amount of description.</li>
  <li>Use&nbsp; break (&lt;br/&gt;) tags to improve readability.</li>
  <li>Subitems can be used to break steps down into smaller steps.</li>
  <li>Not all cheat sheets will require subitems.</li>
  <li>Start subitem label text using action word such as &quot;Input&quot;, &quot;Expand&quot;, 
  &quot;Select&quot;, etc</li>
  <li>For subitem labels, clearly identify interface text using quotes to allow 
  users to differentiate instruction text from interface text they&nbsp; need to 
  locate and interact with.</li>
  <li>Each subitem should be responsible for one atomic task such as inputting 
  one value.</li>
  <li>Always add an &lt;onCompletion&gt; element to the last step of a cheat sheet.</li>
  <li>Test cheat sheets with different sizes for the cheat sheet view.</li>
  <li>Test cheat sheets with the error log view open so you can see if any 
  warnings are written to the log.</li>
</ul>
<h3>Guidelines for Creating a Composite Cheat Sheet</h3>
<ul>
  <li>A composite cheat sheet should contain tasks that are related by a common 
  theme.</li>
  <li>Each task within a composite cheat sheet should have a well defined goal.</li>
  <li>Use &lt;onCompletion&gt; elements to recognize success.</li>
  <li>Task names should&nbsp; be short and concise.</li>
  <li>Complex problems can be solved by using tasks that build upon their 
  predecessors.</li>
  <li>Use skip=&quot;true&quot; if a task is optional.</li>
  <li>For consistency, make sure the simple cheat sheet introduction and name 
  match the introduction and name specified in the composite cheat sheet..</li>
  <li>For task descriptions, clearly identify interface text using bold 
  formatting.</li>
  <li>Sequences should be used only when it is important to enforce order in 
  which tasks can be started.</li>
</ul>

<h3>Related Links</h3>
<p>
<a href="../../org.eclipse.platform.doc.user/reference/ref-cheatsheets.htm">Working with cheat sheets</a><br>
<a href="../../org.eclipse.platform.doc.user/reference/ref-composite-cheatsheets.htm">Working with composite cheat sheets</a><br>
<a href="ua_cheatsheet_simple.htm">Simple cheat sheets</a><br>
<a href="ua_cheatsheet_composite.htm">Composite cheat sheets</a><br>
</p>

</body>
</html>